<html xmlns="http://www.w3.org/1999/xhtml" id="data-transport"
      xmlns:d="docbook">
<head>
  <title>Data Transport</title>
</head>

<body>

<h1>Data Transport</h1>

<!--h2>Overview</h2-->

<d:abstract>
<p>This chapter discusses how to receive and send XML data from remote data sources.
It assumes a general familiary with <a target="_blank" href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP</a>,
<a target="_blank" href="http://www.w3.org/Addressing/URL/url-spec.html">URLs</a> and web application infrastructure.</p>
<fixme>This chapter should/may have Media Transport stuff in it, too.</fixme>
</d:abstract>

<h2>Architectural summary</h2>

<p>LZX provides tags and script APIs for sending and receiving data,
all of which ultimately involve communication with the LPS.  In order
to understand how data is sent to and from a Laszlo application, you will
need to understand the overall Laszlo application architecture.  In
particular, this chapter makes use of the terms <glossterm>client</glossterm>,
<glossterm>server</glossterm>, and <glossterm>back-end</glossterm> as they are defined in <xref
linkend="architecture"/>.  <fixme>You may want to refer to the a
href="" Laszlo Data Flow /a presentation as well.</fixme>
</p>

<p>Whenever the application makes a request for data from a remote
data source or web service, the application <em>always</em> talks back
to the LPS which serves as a proxy for the remote data source.  The
LPS (under application control) may cache data from remote sources as
well.</p>

<h2>Datasets</h2>

<p>Datasets are the LZX representation of XML documents.  They can be
embedded locally in the application (see <xref
linkend="data-structures"/>) or they can hold data that is received
from a remote data source or web service.  Datasets that come from
remote services must have their <attribute>src</attribute> attribute
set.</p>

<h3>The <attribute>src</attribute> attribute</h3>

<p>The <attribute>src</attribute> attribute should be a well-formed
URL that points to the back-end data source that will produce the
data.  This may be an absolute or relative URL.  (All requests made
for relative URLs are relative to the application's URL.)  The URL may
point to a static XML file or a server-side processor (such as JSP, ASP,
PHP, and so on) that produces XML data.</p>

<h4>Supported URL syntaxes</h4>

<h3><event>ondata</event>, <event>onerror</event>, and <event>ontimeout</event> event</h3>

<p>When the application's <classname>LzDataset</classname> receives the data, the
<event>ondata</event> event is sent.  In the case that an error occured
in communicating with the back-end, an <event>onerror</event> event is
sent instead.  And, if there is a timeout (currently hard-coded at 30
seconds) in communicating with the LPS, an <event>ontimeout</event>
event is sent.  The LFC guarentees that each request will generate
exactly one of either <event>ondata</event>, <event>onerror</event>, on
<event>ontimeout</event>.
</p>

<h3>Query parameters</h3>
<todo>to do</todo>

<h3>POST support</h3>
<p>Datasets support both HTTP GET and POST methods for communicating
with the LPS and back-end servers.  The default is GET but this can be
changed with the <code>LzDataset.setQueryType()</code> API.  In
general, requests with large query parameters should be sent via
POST.</p>

<h3><event>onerror</event> and <event>ontimeout</event> events</h3>

<p>The <event>onerror</event> event will fire whenvever there is a
communication problem with the back-end.</p>

<p>The <event>ontimeout</event> event will fire whenever communication
with the LPS times-out.</p>

<p>Time-outs from the LPS to the back-end are reported as error in
the <event>onerror</event> handler.</p>
<?ignore
<h2>Media</h2>
<todo>to do</todo>
?>
<h2>Advanced Topics</h2>

<h3>HTTP Request and Response headers</h3>

<p>In general, the LPS will proxy HTTP request and response headers
to/from the back-end.  However, certain headers are specifically
omitted or modified.</p>
<?ignore
<fixme>include the list here</fixme>
?>
<h3>Cookies</h3>

<p>The LPS will proxy all "Cookie" request headers and all
"<code>Set-Cookie</code>" response headers.  Because of
the domain name restrictions on cookies, the LPS can only properly
proxy these cookie headers when the back-end host is in the same
domain (or a subdomain) or the LPS host.</p>
<?ignore
<h3>GZIP Encoding</h3>

<todo>to do</todo>
?>
<h3>Datasources</h3>

<p>Underlying each dataset that communicates over HTTP is an
<classname>LzDatasource</classname> object.  This object abstracts all protocol
specific communication.  In general, you do not need to use the
datasource object yourself, except for very rare situations.</p>

<fixme>the one situation is when you are running the LPS secure port
on something other than 443; the only place you can specify the
secure port is on the datasource.</fixme>

<h3>Protocols</h3>

<fixme>
Discussion of protocols (http, https, what else?) can come before or after discussion of the datasource class -- I'm not sure
</fixme>

<h2>Performance</h2>
<fixme>to do</fixme>

<h2>Security</h2>
<fixme>to do</fixme>

</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
